Durée estimée: 25 minutes

URL and URL encoding

If you know about URLs, URL encoding, APIs and associated practices and rules, you may skip this part.
Otherwise, run through it a first time to be aware of what is inside, but do not spend too much time. You can come back to it later as you need.Try to catch the idea for now.

What is a Web API (Application Programming Interface) ?

"Web API" historically has been virtually synonymous for “web service”. It describes the functionalities that a web service makes available and how : routines, protocols, inputs, outputs, …
APIs are one of the most common ways technology companies integrate with each other.

In the context of web development, an API is typically defined as a set of Hypertext Transfer Protocol (HTTP) request messages, along with a definition of the structure of response messages.

Note 1 : HTTP requests which you see daily are displayed top-left of your browser in the address box.

Note 2 : within App Inventor, HTTP requests is mainly handled with the webviewer component that can handle html web pages. Another component that can be used is the Canvas component, if and only if the request returns and image file. This is the case for Staticmaps and streetview APIs. HTTP requests can then be used exactly as if it was a local file name :)

What is a URL and how to build it ?

A request message sent on the Web takes the form of a URL (Uniform Resource Locator) described below.

What is a URL

A URL, or commonly a web address, is a reference to a web resource that specifies its location on the net and a mechanism to retrieve it. URLs most commonly reference web pages (http), but are also used for file transfer (ftp), email (mailto), database access (JDBC), and other applications.

For example URLs used for static maps use http and contain :

• a scheme (https, ...),
• a host (maps.googleapis.com),
• a path (/maps/api/staticmap),
• and a query : (center=37.7,-122.4&size=320x320&zoom=14&maptype=roadmap),

leading to the following URL : https://maps.googleapis.com/maps/api/staticmap?center=37.77,-122.45&size=320x320&zoom=14&maptype=roadmap

Query string in the URL

As illustrated in above example, the query string is the part of a URL that carries the specification of what is requested as the returned result. It comes after the host and path and generally follows the question mark “?”.
The query is commonly encoded as field/value pairs separated by & delimiters :
field1=value1&field2=value2&field3=value3...

The query fields and values are defined by each service provider in the documentation of its API. For example in the following URL (which you can copy/paste into your web browser address), the query string is what follows the question mark. The delimiter between attribute-value pairs is ‘&’
https://maps.googleapis.com/maps/api/staticmap?center=37.777,-122.451&size=320x320&zoom=14&maptype=roadmap
In this example the field named “center” has the value “37.777,-122.451” and the field named “size” has the value “320x320”.
When a field has multiple values, another delimiter is often used. For example, the ‘|’ character separates coordinate values in the static maps API, as in the following list of marker coordinates :
&markers=color:blue|label:x|37.78,-122.46|37.77,-122.46|37.78,-122.45

You will meet other query formats where parameters do not follow a question mark.
This is the case for open street maps or Google maps where wueries can take the following form :
http://www.openstreetmap.org/#map=17/48.83577/2.30503&layers=H
https://www.google.fr/maps/@37.7760491,-122.4488144,16.9z
However the URL organization remains similar and you should have no major difficulty to handle them.

URL encoding

Some characters have a special meaning in a URL : they are "reserved characters".
For example, the "space" character is used as a separator within HTTP messages, and we cannot use it "as is" within query parameters such as a postal address.
These forbidden or “reserved” characters must be replaced in the query : this is called " URL encoding". Reserve characters are replaced by % and their hexadecimal value (see tables below). Replacement is mandatory for “reserved characters” and recommended for other characters which are neither “reserved” or “Non reserved”.
The reserved space character (which is very frequent) may also be replaced by ’+’.
Within app Inventor, this is done by the uri Encode block of the Web component, in the connectivity drawer.

Mandatory translation values for reserved characters (after percent-encoding)

 !   #   $   &   '   (   )   *   +   ,   /   :   ;   =   ?   @   [   ]		
%21 %23 %24 %26 %27 %28 %29 %2A %2B %2C %2F %3A %3B %3D %3F %40 %5B %5D		
                

Recommended but non mandatory translation values for other (neither reserved or non reserved)

  Newline          space   "   %   -   .   <   >   \   ^   _   `   {   |   }   ~
%0A or %0D or %0A   %20   %22 %25 %2D %2E %3C %3E %5C %5E %5F %60 %7B %7C %7D %7E
                

For example,

&markers=color:blue|label:x|37.78,-122.46|37.77,-122.46|37.78,-122.45

should be replaced by

&markers=color:blue%7C label:x%7C 37.78,-122.46%7C 37.77,-122.46%7C 37.78,-122.45

and

University of San Francisco

should be replaced by

University%20of%20San%20Francisco

or by

University+of+San+Francisco

Mapping APIs and associated App Inventor components

• the “webViewer” component can display web pages in general, like a browser : http://ai2.appinventor.mit.edu/reference/components/userinterface.html#WebViewer The webviewer component can be associated with several APIs. We will illustrates it’s use in 2 solutions :
  • dynamic maps from Web services (solution 1)
  • with fusion tables (solution 3)
• the “canvas” component can only display image files, but if a URL returns a file, then this URL can be used exactly like a local image file name ! The canvas component can be associated with several APIs, and we will illustrate its use with the google Maps and streetview static API (solution 4)
• he ActTivity Starter component can start a new App or activity such as Google Maps, and tell it what to do with a DataURI. This API is the Intents API. We will illustrate its use with the google Maps App (solution 2)

Besides showing what a secondary App can do, we will show examples with the web viewer and the canvas to understand what each one can do and how they differ :

• the webviewer component is very general, but the App loses control on window events. What is nice is that you have the web server interactivity,
• The backdoor solution to recover control with a web viewer is to manage data and mapping on the cloud side : this is what App Inventor can do with fusion tables do,
• the canvas component has no native functions for mapping, but it keeps control on window events (click,drag, …), so that you can decide to do whatever you want on each event (but you have to do the coding work) We may also mention, the “Web” component which has blocks to query and process web data. We will not use it, but if you wish, look at the tutorial here http://appinventor.mit.edu/explore/ai2/stockquotes.html